#%RAML 0.8
title: Patrons
version: v1
baseUri: http://github.com/org/folio/lsp-apis
protocols: [ HTTPS ]

documentation:
  - title: Patron API in the circulation context
    content: <b>This documents the API calls that can be made for users to fulfill circulation functionality</b>

schemas:
  - last_modified: !include ../_schemas/last_modified.schema
  - patrons: !include ../_schemas/patrons.schema
  - patron: !include ../_schemas/patron.schema
  - fines:  !include ../_schemas/fines.schema
  - fine:  !include ../_schemas/fine.schema
  - item: !include ../_schemas/item.schema
  - loans: !include  ../_schemas/loans.schema
  - loan: !include  ../_schemas/loan.schema
  - item_requests: !include  ../_schemas/item_requests.schema
  - item_request: !include  ../_schemas/item_request.schema

traits:
  - secured: !include ../../raml-util/traits/auth.raml
  - orderable: !include ../../raml-util/traits/orderable.raml
  - pageable:  !include ../../raml-util/traits/pageable.raml
  - searchable: !include ../../raml-util/traits/searchable.raml
  - payment: !include ../../raml-util/traits/payment.raml
  - barcode_id: !include ../../raml-util/traits/barcode_id.raml
  - item_id: !include ../../raml-util/traits/item_id.raml
  - reason: !include ../../raml-util/traits/reason.raml
  - language: !include ../../raml-util/traits/language.raml
  - time-period: !include ../../raml-util/traits/time-period.raml

resourceTypes:
  - collection: !include ../../raml-util/rtypes/collection.raml
  - collection-item: !include ../../raml-util/rtypes/item-collection.raml
  - get-only: !include ../../raml-util/rtypes/get-only.raml
  - post-empty-body: !include ../../raml-util/rtypes/post-empty-body.raml

/patrons:
  displayName: Patrons
  type:
    collection:
      exampleCollection: !include  ../_examples/patron_get.sample
      exampleItem: !include ../_examples/patron_post.sample
      schemaCollection: patrons
      schemaItem: patron
  get:
    is: [
      searchable: {description: "with valid searchable fields: for example lastname", example: "[\"patron.status\", \"ACTIVE\", \"=\"]"},
      orderable: {fieldsList: "field A, field B"},
      pageable
    ]
  /fines:
    displayName: Fees
    description: Allows for searching fines across all patrons - such as all fines with amount due > X
    type:
      get-only:
        exampleCollection: !include  ../_examples/fine_get.sample
        schema: fines
    get:
      is: [
        searchable: {description: "with valid searchable fields: for example lastname", example: "[\"fine_data.fine_amount\",  150, \">\"]"},
        orderable: {fieldsList: "field A, field B"},
        pageable
    ]
  /{patronId}:
    type:
      collection-item:
        exampleItem: !include ../_examples/patron_get.sample
        schema: patron
    /fines:
      displayName: Fees
      description: Fines associated with a specific patron
      type:
        collection:
          exampleCollection: !include  ../_examples/fine_get.sample
          exampleItem: !include ../_examples/fine_post.sample
          schemaCollection: fines
          schemaItem: fine
      get:
        is: [
          searchable: {description: "with valid searchable fields: for example amount", example: "[\"fine_data.fine_amount\", 100, \">\"]"},
          orderable: {fieldsList: "field A, field B"},
          pageable
        ]
      /{fineId}:
        description:  <ul><li>Retrieves the user fine for a particular user id and fine id<br><li>Update a fine for a specific user<br><li>Delete fineId belonging to patronId<br><li>Pay, waive, or dispute a fine</ul>
        type:
          collection-item:
            exampleItem: !include ../_examples/fine_get.sample
            schema: fine
        post:
          description: Applies the operation specified in the query parameter to a specific fine.
          is: [payment]
          responses:
            201:
              description: "Returns a newly created item, with server-controlled fields like 'id' populated"
              headers:
                Location:
                  description: URI to the created fine item
              body:
                application/json:
                  example: !include ../_examples/fine_get.sample
                  schema: fine
            400:
              description: "Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response."
              body:
                text/plain:
                  example: |
                    "unable to pay fine -- malformed JSON at 13:3"
            500:
              description: "Internal server error, e.g. due to misconfiguration"
              body:
                text/plain:
                  example: "Internal server error, contact administrator"
    /loans:
      displayName: User loans
      description:  <ul><li>Retrieve a list of loans for a user<br><li>Add a loan for a user</ul>
      type:
        collection:
          exampleCollection: !include  ../_examples/loan_get.sample
          exampleItem: !include ../_examples/loan_post.sample
          schemaCollection: loans
          schemaItem: loan
      get:
        is: [
          pageable,
          orderable: {fieldsList: "field A, field B"}
          ]
      /{loanId}:
        displayName: A loan
        description: <ul><li>Retrieves the loan for a particular user id and loan id<br><li>Update a specific loan for a specific user<br><li>Cancel a user's loan<br><li>Renew a loan</ul>
        type:
          collection-item:
            exampleItem: !include ../_examples/loan_get.sample
            schema: loan
        post:
          description: Renew a loan for patronId
          is: [time-period]
          queryParameters:
            operation:
              description: |
                Type of operation = renew
              enum: [renew]
              required: true
              default: renew
              example: renew
          responses:
            201:
              description: "Returns a newly created item, with server-controlled fields like 'id' populated"
              headers:
                Location:
                  description: URI to the created fine item
              body:
                application/json:
                  example: !include ../_examples/loan_get.sample
                  schema: loan
            400:
              description: "Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response."
              body:
                text/plain:
                  example: |
                    "unable to renew loan -- malformed JSON at 13:3"
            500:
              description: "Internal server error, e.g. due to misconfiguration"
              body:
                text/plain:
                  example: "Internal server error, contact administrator"
    /requests:
      displayName: User requests
      description:  <ul><li>Retrieve a list of requests made by a user<br><li>Add a request for an item by a user</ul>
      type:
        collection:
          exampleCollection: !include  ../_examples/item_request_get.sample
          exampleItem: !include ../_examples/item_request_post.sample
          schemaCollection: item_requests
          schemaItem: item_request
      get:
        is: [pageable]
        queryParameters:
          status:
            description: |
              Return requests that are either only active (default) or history of all requests (anonymized requests will not be returned)
            enum: [active, history]
            required: true
            default: active
          request_type:
            description: Filter by a specific request type
            enum: [HOLD, DIGITIZATION, BOOKING, ALL]
            required: false
            default: ALL
      post:
        description: Create a request for a specific item id
        is: [item_id]
      /{requestId}:
        displayName: RequestId
        description: <ul><li>Retrieves the request for a particular user id and request id<br><li>Update a specific request for a specific user<br><li>Cancel a user's request</ul>
        type:
          collection-item:
            exampleItem: !include ../_examples/item_request_get.sample
            schema: item_request
        delete:
          description: Cancel a user's request
          is: [reason]
